😎 Merged manually by @heyong4725 - details.

@GHX5T-SOL the Trunk merge queue failed for this PR.

See the Trunk merge-status comment for details.

Posted as a new comment so GitHub sends an email — Trunk's sticky comment is edited in place and won't trigger a notification.

Rebased this branch on current origin/main after the merge-queue pip-release all green failure. The diff is still docs-only.

Validation:

• git diff --check origin/main...HEAD
• git diff origin/main...HEAD | gitleaks detect --pipe --redact --no-banner -> no leaks found

/trunk merge

An error occurred while submitting your PR to the queue: Only users that are a part of this repo's Trunk organization or have write permissions to the repo can submit a PR to the queue

Did a verification pass on the table. Every error message fragment was sourced from a real codebase string — I grep-checked all 13 and they all match. The coordinator heartbeat timeout (20s) literal is preserved verbatim from binaries/daemon/src/lib.rs:993. Nice sourcing.

Two notes worth flagging:

1. dora logs --daemon is not a real flag

In the "failed to register node with dora-daemon" row, the Fix column says Check dora logs --daemon. That flag doesn't exist. target/debug/dora logs --help shows the actual surface:

--all-nodes, --tail, --local, --since, --until, --level,
--log-format, --log-filter, --grep, --coordinator-addr, --coordinator-port

If the intent was "read the daemon's own logs," there isn't a first-class path for that — closest is dora logs --local (reads the out/<dataflow>/log_*.jsonl files which include daemon-side log entries) or grepping coordinator/daemon process stderr from dora up's spawn. Suggest reframing as something like:

Inspect the daemon's stderr (the process started by dora up); confirm the node ID and dataflow ID match the current run.

2. Positional dora logs <dataflow> <node> will conflict with #1883

Three of your Fix cells use dora logs <dataflow> <node> (the old positional shape). Your other PR (#1883) deprecates that in favor of dora logs <dataflow> --node <node>. If #1883 lands first, this doc is instantly stale on those rows.

Two options depending on merge order:

• Land docs: add debugging error lookup table #1884 first → update the three positional uses in feat(cli): use --node for dora logs node selection #1883 as part of its doc sweep
• Land feat(cli): use --node for dora logs node selection #1883 first → update the three positional uses here in a follow-up commit before merge

Either way, the rows affected are: "node ... not connected", "node ... channel closed", and possibly "node ... channel full" (it inspects logs implicitly).

Aside from those, the table is a solid addition. Verified dora node info -d, dora param list/set, DORA_DAEMON_LOCAL_LISTEN_PORT, and dora down/up all behave as the doc describes.

Addressed the debugging-table/doc syntax notes in 917b4f2.\n\nChanges:\n- Replaced the nonexistent dora logs --daemon guidance with the suggested daemon-stderr direction for the process started by dora up.\n- Updated stale positional node examples in docs/debugging.md to use dora logs <dataflow> --node <node>.\n- Updated the local-log example to dora logs --local --node <node>.\n\nValidation:\n- grep confirmed no remaining dora logs --daemon references in docs/debugging.md\n- grep confirmed no remaining stale dora logs <dataflow> <node> examples in docs/debugging.md; the only remaining match is the valid dataflow-only dora logs <uuid> form\n- git diff --check\n- changed-doc diff gitleaks scan -> no leaks found

Nice work on the error table — verified all 13 error fragments exist in the codebase, the "likely cause" and "next step" columns are accurate and actionable.

One issue to fix before this can land

The 7 dora logs --node <name> insertions are invalid CLI syntax. dora logs takes the node name as a positional argument:

dora logs <dataflow> <node>

See binaries/cli/src/command/logs.rs:34 — the node: field has #[clap(value_name = "NAME")] but no #[clap(long)], so it's positional only:

/// Show logs for the given node (omit with --all-nodes)
#[clap(value_name = "NAME")]
pub node: Option<NodeId>,

And dora logs --help confirms:

Usage: dora logs [OPTIONS] [UUID_OR_NAME] [NAME]

A user following this PR's examples will hit error: unexpected argument '--node' found.

7 lines to revert

The sister doc docs/cli.md:546 already shows the canonical dora logs [UUID_OR_NAME] [NODE] [OPTIONS] and the example at docs/cli.md:1656 (correctly left untouched by this PR) uses the positional form. Aligning with that keeps the two docs consistent.

What's solid (don't change)

The error table itself (lines 117-138) is the meat of the PR and it's well-done:

Each "likely cause" reads accurate and each "next step" is a runnable command. This is the right level of detail for the lookup table #1878 asked for.

Also worth checking

Branch is 22 commits behind main (last sync 2026-05-20 at 271a0470). A git pull --rebase origin main before merging would catch any unexpected conflicts and put your work on top of current main.

TL;DR

• Revert the 7 --node insertions to positional (1-line sed job: sed -i '' 's| --node \([a-zA-Z0-9_-]*\)| \1|g' docs/debugging.md, then spot-check)
• Rebase on main to pick up the 6 days of work that landed since
• Then this is good to land

Correction to my earlier review — I missed PR #1883.

PR #1883 (also from @GHX5T-SOL, addressing issue #1880) is the upstream CLI change that adds the --node/-n flag to dora logs. With that PR landed, the --node syntax this PR introduces in docs/debugging.md is exactly correct.

My earlier P1 was wrong. Sorry for the noise — I should have looked at the contributor's other open PRs before flagging the syntax.

Updated recommendation

Suggested merge sequence

1. feat(cli): use --node for dora logs node selection #1883 lands first — it ships the --node CLI flag + updates docs/debugging.md in the same 5 places this PR does (plus README, docs/cli, docs/logging, docs/distributed-deployment, docs/quickstart).
2. Rebase this PR on main — after feat(cli): use --node for dora logs node selection #1883 lands, the 5 syntax-update lines in this PR will be duplicates already on main. git pull --rebase origin main will collapse the diff to just the new error table content + the TOC link.
3. This PR merges cleanly with a focused diff: ~25 lines of new error-table content in docs/debugging.md.

If you'd rather land #1884 first, you'd need to coordinate with #1883's docs/debugging.md diff manually — but the rebase path is much simpler.

What still stands

• All 13 error fragments in the table are verified to exist in the codebase (the grep checks I posted earlier still hold).
• The error table content is the right level of detail for the lookup table docs: visual diagrams in core onboarding docs + structured error-message table #1878 asked for.
• Branch is still 22+ commits behind main, so a rebase is worth doing regardless.

Rebased on main for you (PR opted into maintainer edits, so I pushed directly). New head: 31bf10000.

Now that #1883 has landed (f8aebe18), the --node syntax this PR uses in docs/debugging.md is correct, and the 5 syntax-update lines that were originally in this diff are already on main — so the rebase collapsed them out automatically.

Before rebase: 1 file changed, 31+/5- (TOC link + error table + 5 syntax adjustments)
After rebase: 1 file changed, 26+/0- (TOC link + error table only)

The error table content is unchanged — all 13 verified error fragments still there.

CI will rerun on the new head; once green, this is ready to merge.